
/*
 * Copyright 2002-2020 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2020原作者。
 *
 *根据Apache许可证2.0版（“许可证”）获得许可；
 *除非符合许可证，否则不得使用此文件。
 *您可以在以下地址获取许可证副本：
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，软件
 *根据许可证分发的内容是按“原样”分发的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限和
 *许可证下的限制。
 */

package org.springframework.aop.framework;

import org.aopalliance.aop.Advice;

import org.springframework.aop.Advisor;
import org.springframework.aop.TargetClassAware;
import org.springframework.aop.TargetSource;

/**
 * Interface to be implemented by classes that hold the configuration
 * of a factory of AOP proxies. This configuration includes the
 * Interceptors and other advice, Advisors, and the proxied interfaces.
 *
 * <p>Any AOP proxy obtained from Spring can be cast to this interface to
 * allow manipulation of its AOP advice.
 *
 * @author Rod Johnson
 * @author Juergen Hoeller
 * @since 13.03.2003
 * @see org.springframework.aop.framework.AdvisedSupport
 */
/**
 *由保存配置的类实现的接口
 *AOP代理的工厂。此配置包括
 *拦截器和其他建议、顾问和代理接口。
 *
 *＜p＞从Spring获得的任何AOP代理都可以强制转换到此接口
 *允许操作其AOP建议。
 *
 *@作者Rod Johnson
 *@作者Juergen Hoeller
 *@自2003年3月13日
 *@参见org.springframework.aop.framework.AdvisedSupport
 */
public interface Advised extends TargetClassAware {

	/**
	 * Return whether the Advised configuration is frozen,
	 * in which case no advice changes can be made.
	 */
	/**
	 *返回Advised配置是否已冻结，
	 *在这种情况下，不能进行建议更改。
	 */
	boolean isFrozen();

	/**
	 * Are we proxying the full target class instead of specified interfaces?
	 */
	/**
	 *我们是否代理完整的目标类而不是指定的接口？
	 */
	boolean isProxyTargetClass();

	/**
	 * Return the interfaces proxied by the AOP proxy.
	 * <p>Will not include the target class, which may also be proxied.
	 */
	/**
	 *返回AOP代理代理的接口。
	 *＜p＞将不包括目标类，它也可以被代理。
	 */
	Class<?>[] getProxiedInterfaces();

	/**
	 * Determine whether the given interface is proxied.
	 * @param intf the interface to check
	 */
	/**
	 *确定给定接口是否被代理。
	 *@param intf要检查的接口
	 */
	boolean isInterfaceProxied(Class<?> intf);

	/**
	 * Change the {@code TargetSource} used by this {@code Advised} object.
	 * <p>Only works if the configuration isn't {@linkplain #isFrozen frozen}.
	 * @param targetSource new TargetSource to use
	 */
	/**
	 *更改此｛@code Advised｝对象使用的｛@codeTargetSource｝。
	 *＜p＞仅当配置不是｛@linkplain#isFrozen冻结｝时才有效。
	 *@param targetSource要使用的新targetSource
	 */
	void setTargetSource(TargetSource targetSource);

	/**
	 * Return the {@code TargetSource} used by this {@code Advised} object.
	 */
	/**
	 *返回此｛@code Advised｝对象使用的｛@codeTargetSource｝。
	 */
	TargetSource getTargetSource();

	/**
	 * Set whether the proxy should be exposed by the AOP framework as a
	 * {@link ThreadLocal} for retrieval via the {@link AopContext} class.
	 * <p>It can be necessary to expose the proxy if an advised object needs
	 * to invoke a method on itself with advice applied. Otherwise, if an
	 * advised object invokes a method on {@code this}, no advice will be applied.
	 * <p>Default is {@code false}, for optimal performance.
	 */
	/**
	 *设置AOP框架是否应将代理公开为
	 *｛@link ThreadLocal｝用于通过｛@linkAoPContext｝类进行检索。
	 *＜p＞如果建议的对象需要
	 *在应用了建议的情况下调用自身的方法。否则，如果
	 *被建议的对象调用｛@codethis｝上的方法，则不会应用任何建议。
	 *＜p＞为获得最佳性能，默认值为｛@code false｝。
	 */
	void setExposeProxy(boolean exposeProxy);

	/**
	 * Return whether the factory should expose the proxy as a {@link ThreadLocal}.
	 * <p>It can be necessary to expose the proxy if an advised object needs
	 * to invoke a method on itself with advice applied. Otherwise, if an
	 * advised object invokes a method on {@code this}, no advice will be applied.
	 * <p>Getting the proxy is analogous to an EJB calling {@code getEJBObject()}.
	 * @see AopContext
	 */
	/**
	 *返回工厂是否应将代理公开为｛@link ThreadLocal｝。
	 *＜p＞如果建议的对象需要
	 *在应用了建议的情况下调用自身的方法。否则，如果
	 *被建议的对象调用｛@codethis｝上的方法，则不会应用任何建议。
	 *＜p＞获取代理类似于EJB调用｛@code getEJBObject（）｝。
	 *@参见AopContext
	 */
	boolean isExposeProxy();

	/**
	 * Set whether this proxy configuration is pre-filtered so that it only
	 * contains applicable advisors (matching this proxy's target class).
	 * <p>Default is "false". Set this to "true" if the advisors have been
	 * pre-filtered already, meaning that the ClassFilter check can be skipped
	 * when building the actual advisor chain for proxy invocations.
	 * @see org.springframework.aop.ClassFilter
	 */
	/**
	 *设置是否预筛选此代理配置，以便仅
	 *包含适用的顾问（匹配此代理的目标类）。
	 *＜p＞默认值为“false”。如果顾问已经
	 *已预先筛选，这意味着可以跳过ClassFilter检查
	 *当为代理调用构建实际的顾问链时。
	 *@参见org.springframework.aop.ClassFilter
	 */
	void setPreFiltered(boolean preFiltered);

	/**
	 * Return whether this proxy configuration is pre-filtered so that it only
	 * contains applicable advisors (matching this proxy's target class).
	 */
	/**
	 *返回此代理配置是否已预先筛选，以便仅
	 *包含适用的顾问（匹配此代理的目标类）。
	 */
	boolean isPreFiltered();

	/**
	 * Return the advisors applying to this proxy.
	 * @return a list of Advisors applying to this proxy (never {@code null})
	 */
	/**
	 *返回申请此代理的顾问。
	 *@返回应用于此代理的顾问列表（从不｛@code null｝）
	 */
	Advisor[] getAdvisors();

	/**
	 * Return the number of advisors applying to this proxy.
	 * <p>The default implementation delegates to {@code getAdvisors().length}.
	 * @since 5.3.1
	 */
	/**
	 *返回申请此代理的顾问数量。
	 *＜p＞默认实现委托给｛@code getAdvisors（）.length｝。
	 *@自5.3.1
	 */
	default int getAdvisorCount() {
		return getAdvisors().length;
	}

	/**
	 * Add an advisor at the end of the advisor chain.
	 * <p>The Advisor may be an {@link org.springframework.aop.IntroductionAdvisor},
	 * in which new interfaces will be available when a proxy is next obtained
	 * from the relevant factory.
	 * @param advisor the advisor to add to the end of the chain
	 * @throws AopConfigException in case of invalid advice
	 */
	/**
	 *在顾问链的末端添加顾问。
	 *＜p＞顾问可以是一个｛@link org.springframework.aop.InventionAdvisor｝，
	 *在下一次获取代理时，新的接口将可用
	 *来自相关工厂。
	 *@param advisor要添加到链末端的顾问
	 *如果建议无效，@throws AopConfigException
	 */
	void addAdvisor(Advisor advisor) throws AopConfigException;

	/**
	 * Add an Advisor at the specified position in the chain.
	 * @param advisor the advisor to add at the specified position in the chain
	 * @param pos position in chain (0 is head). Must be valid.
	 * @throws AopConfigException in case of invalid advice
	 */
	/**
	 *在链条的指定位置添加Advisor。
	 *@param advisor要在链中指定位置添加的顾问
	 *@param在链中的位置（0是头部）。必须有效。
	 *如果建议无效，@throws AopConfigException
	 */
	void addAdvisor(int pos, Advisor advisor) throws AopConfigException;

	/**
	 * Remove the given advisor.
	 * @param advisor the advisor to remove
	 * @return {@code true} if the advisor was removed; {@code false}
	 * if the advisor was not found and hence could not be removed
	 */
	/**
	 *删除给定的顾问。
	 *@param advisor要删除的顾问
	 *@return｛@code true｝如果顾问已删除；｛@code false｝
	 *如果找不到顾问，因此无法删除
	 */
	boolean removeAdvisor(Advisor advisor);

	/**
	 * Remove the advisor at the given index.
	 * @param index the index of advisor to remove
	 * @throws AopConfigException if the index is invalid
	 */
	/**
	 *删除给定索引处的顾问。
	 *@param索引要删除的顾问的索引
	 *如果索引无效，@throws AopConfigException
	 */
	void removeAdvisor(int index) throws AopConfigException;

	/**
	 * Return the index (from 0) of the given advisor,
	 * or -1 if no such advisor applies to this proxy.
	 * <p>The return value of this method can be used to index into the advisors array.
	 * @param advisor the advisor to search for
	 * @return index from 0 of this advisor, or -1 if there's no such advisor
	 */
	/**
	 *返回给定顾问的索引（从0开始），
	 *或-1，如果没有此类顾问适用于此代理。
	 *＜p＞此方法的返回值可用于索引顾问数组。
	 *@param advisor要搜索的顾问
	 *@return索引来自该顾问的0，如果没有该顾问，则为-1
	 */
	int indexOf(Advisor advisor);

	/**
	 * Replace the given advisor.
	 * <p><b>Note:</b> If the advisor is an {@link org.springframework.aop.IntroductionAdvisor}
	 * and the replacement is not or implements different interfaces, the proxy will need
	 * to be re-obtained or the old interfaces won't be supported and the new interface
	 * won't be implemented.
	 * @param a the advisor to replace
	 * @param b the advisor to replace it with
	 * @return whether it was replaced. If the advisor wasn't found in the
	 * list of advisors, this method returns {@code false} and does nothing.
	 * @throws AopConfigException in case of invalid advice
	 */
	/**
	 *更换给定的顾问。
	 *<p><b>注意：</b>如果顾问是{@link.org.springframework.aop.InventionAdvisor}
	 *如果替换不是或实现不同的接口，代理将需要
	 *重新获取，否则旧接口将不受支持，而新接口
	 *不会实施。
	 *@param a要替换的顾问
	 *@param b替换它的顾问
	 *@return是否被替换。如果在
	 *该方法返回｛@code false｝并且不执行任何操作。
	 *如果建议无效，@throws AopConfigException
	 */
	boolean replaceAdvisor(Advisor a, Advisor b) throws AopConfigException;

	/**
	 * Add the given AOP Alliance advice to the tail of the advice (interceptor) chain.
	 * <p>This will be wrapped in a DefaultPointcutAdvisor with a pointcut that always
	 * applies, and returned from the {@code getAdvisors()} method in this wrapped form.
	 * <p>Note that the given advice will apply to all invocations on the proxy,
	 * even to the {@code toString()} method! Use appropriate advice implementations
	 * or specify appropriate pointcuts to apply to a narrower set of methods.
	 * @param advice the advice to add to the tail of the chain
	 * @throws AopConfigException in case of invalid advice
	 * @see #addAdvice(int, Advice)
	 * @see org.springframework.aop.support.DefaultPointcutAdvisor
	 */
	/**
	 *将给定的AOP联盟建议添加到建议（拦截器）链的尾部。
	 *＜p＞这将被包装在DefaultPointcutAdvisor中，其中的切入点始终
	 *应用，并从｛@code getAdvisors（）｝方法返回。
	 *＜p＞注意，给定的建议将应用于代理上的所有调用，
	 *甚至是{@codetoString（）}方法！使用适当的建议实施
	 *或指定适当的切入点以应用于较窄的方法集。
	 *@param advice要添加到链尾部的建议
	 *如果建议无效，@throws AopConfigException
	 *@参见#addAdvice（int，Advice）
	 *@参见org.springframework.aop.support.DefaultPointcutAdvisor
	 */
	void addAdvice(Advice advice) throws AopConfigException;

	/**
	 * Add the given AOP Alliance Advice at the specified position in the advice chain.
	 * <p>This will be wrapped in a {@link org.springframework.aop.support.DefaultPointcutAdvisor}
	 * with a pointcut that always applies, and returned from the {@link #getAdvisors()}
	 * method in this wrapped form.
	 * <p>Note: The given advice will apply to all invocations on the proxy,
	 * even to the {@code toString()} method! Use appropriate advice implementations
	 * or specify appropriate pointcuts to apply to a narrower set of methods.
	 * @param pos index from 0 (head)
	 * @param advice the advice to add at the specified position in the advice chain
	 * @throws AopConfigException in case of invalid advice
	 */
	/**
	 *在建议链中的指定位置添加给定的AOP联盟建议。
	 *＜p＞这将被包装在｛@linkorg.springframework.aop.support.DefaultPointcutAdvisor｝中
	 *具有始终适用的切入点，并从｛@link#getAdvisors（）｝返回
	 *方法。
	 *＜p＞注意：给定的建议将应用于代理上的所有调用，
	 *甚至是{@codetoString（）}方法！使用适当的建议实施
	 *或指定适当的切入点以应用于较窄的方法集。
	 *@param pos索引从0（头）
	 *@param advice要在建议链中的指定位置添加的建议
	 *如果建议无效，@throws AopConfigException
	 */
	void addAdvice(int pos, Advice advice) throws AopConfigException;

	/**
	 * Remove the Advisor containing the given advice.
	 * @param advice the advice to remove
	 * @return {@code true} of the advice was found and removed;
	 * {@code false} if there was no such advice
	 */
	/**
	 *拆下包含给出建议的Advisor。
	 *@param建议删除建议
	 *找到并删除了建议的@return｛@code true｝；
	 *｛@code false｝如果没有这样的建议
	 */
	boolean removeAdvice(Advice advice);

	/**
	 * Return the index (from 0) of the given AOP Alliance Advice,
	 * or -1 if no such advice is an advice for this proxy.
	 * <p>The return value of this method can be used to index into
	 * the advisors array.
	 * @param advice the AOP Alliance advice to search for
	 * @return index from 0 of this advice, or -1 if there's no such advice
	 */
	/**
	 *返回给定AOP联盟建议的索引（从0开始），
	 *或-1，如果没有此类建议是该代理的建议。
	 *＜p＞此方法的返回值可用于索引到
	 *顾问阵列。
	 *@param advice要搜索的AOP联盟建议
	 *@return索引来自此建议的0，如果没有此建议，则为-1
	 */
	int indexOf(Advice advice);

	/**
	 * As {@code toString()} will normally be delegated to the target,
	 * this returns the equivalent for the AOP proxy.
	 * @return a string description of the proxy configuration
	 */
	/**
	 *由于｛@code toString（）｝通常会被委托给目标，
	 *这将返回AOP代理的等效值。
	 *@返回代理配置的字符串描述
	 */
	String toProxyConfigString();

}
